/*
 ------------------------------------------------------------------------------
 Copyright (C) 2006-2007 Team Blur.

 This file is part of the Quantum Engine source code.

 The Quantum Engine source code is free software; you can redistribute it and/or
 modify it under the terms of the GNU General Public License as published by
 the Free Software Foundation; either version 2 of the License, or (at your
 option) any later version.

 The Quantum Engine source code is distributed in the hope that it will be useful,
 but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
 or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
 more details.

 You should have received a copy of the GNU General Public License along with
 the Quantum Engine source code; if not, write to the Free Software Foundation, Inc.,
 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
 ------------------------------------------------------------------------------
*/


#ifndef __S_PUBLIC_H__
#define __S_PUBLIC_H__


// Loads and prepares environmental reverberation effects for a given map
void			S_LoadReverbs (const char *name);

// Loads and registers the given sound shader
soundShader_t *	S_RegisterSoundShader (const char *name);

// Emitters are used to play sounds in the world.
// When an emitter is freed all sounds can continue playing until completed, or
// they can be stopped immediately.
int				S_AddSoundEmitter (int listenerId, const odVec3 &position, const odVec3 &velocity, bool underwater, int area);
void			S_UpdateSoundEmitter (int emitterHandle, int listenerId, const odVec3 &position, const odVec3 &velocity, bool underwater, int area);
void			S_FreeSoundEmitter (int emitterHandle, bool stopSounds);

// Plays a sound on the given channel of the given emitter.
// SOUND_CHANNEL_ANY will never override a playing sound.
// Returns the length of the sound in milliseconds, or 0 if the sound could not
// be played for some reason.
int				S_PlaySoundOnEmitter (int emitterHandle, int channelId, soundShader_t *soundShader);

// Stops all sounds playing on the given channel of the given emitter.
// SOUND_CHANNEL_ANY will stop all playing sounds.
void			S_StopSoundOnEmitter (int emitterHandle, int channelId);

// Updates listener parameters
void			S_PlaceListener (int listenerId, int time, const odVec3 &position, const odVec3 &velocity, const odMat3 &axis, bool underwater, int area);

// Returns a shake amplitude for the current listener position
float			S_ShakeAmplitudeForListener (void);

// Local sounds always play at full volume with no spatialization
void			S_PlayLocalSound (soundShader_t *soundShader);

// Background music streaming.
// Note that only OGG files are supported.
void			S_PlayBackgroundMusic (const char *name);
void			S_StopBackgroundMusic (void);

// Cinematic streaming.
// The sound data must be 16 bits wide.
void			S_StreamRawSamples (const void *data, int samples, int rate, int channels);

// Stops all playing sounds
void			S_StopAllSounds (void);

// Updates all playing sounds
void			S_Update (int frameTime);

// Enumerates sound shader scripts using a callback.
// This is for use by integrated editors.
void			S_EnumSoundShaderScripts (void (*callback)(const char *));

// Allows other subsystems to get the current AL configuration
void			S_GetALConfig (alConfig_t *config);

// Activates or deactivates sound output.
// This should be called when the main window gains or loses focus.
void			S_Activate (bool active);

// Initializes the sound subsystem.
// If all is false, the OpenAL subsystem will not be initialized, which is
// useful for flushing all data and resetting the state.
void			S_Init (bool all);

// Shuts down the sound subsystem.
// If all is false, the OpenAL subsystem will not be shut down, which is useful
// for flushing all data and resetting the state.
void			S_Shutdown (bool all);


#endif	// __S_PUBLIC_H__
